Skip to content

Add Markdown documentation linting#2446

Open
msteslov wants to merge 1 commit into
open-quantum-safe:mainfrom
msteslov:add-markdown-linter
Open

Add Markdown documentation linting#2446
msteslov wants to merge 1 commit into
open-quantum-safe:mainfrom
msteslov:add-markdown-linter

Conversation

@msteslov
Copy link
Copy Markdown

@msteslov msteslov commented May 25, 2026 •
edited
Loading

Fixes #1785.

Adds a Markdown linting job to the basic CI workflow using rumdl.

Testing:

  • rumdl check --config .rumdl.toml --respect-gitignore --exclude 'build,**/build' .
  • actionlint -shellcheck "" .github/workflows/basic.yml
  • Does this PR change the input/output behaviour of a cryptographic algorithm (i.e., does it change known answer test values)? (If so, a version bump will be required from x.y.z to x.(y+1).0.)
  • Does this PR change the list of algorithms available -- either adding, removing, or renaming? Does this PR otherwise change an API? (If so, PRs in fully supported downstream projects dependent on these, i.e., oqs-provider will also need to be ready for review and merge by the time this is merged. Also, make sure to update the list of algorithms in the continuous benchmarking files: .github/workflows/kem-bench.yml and sig-bench.yml)

AI assistance was used for repository inspection and drafting; I reviewed and verified the final changes.

@msteslov msteslov force-pushed the add-markdown-linter branch from 26adcca to ecf42c5 Compare May 25, 2026 08:41
dstebila
dstebila previously approved these changes May 25, 2026
View reviewed changes
@dstebila dstebila self-requested a review May 25, 2026 11:50
xuganyu96
xuganyu96 previously approved these changes May 25, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@xuganyu96 xuganyu96 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Thank you for the contribution.

@xuganyu96 xuganyu96 added this to the 0.16.0 milestone May 25, 2026
@coveralls
Copy link
Copy Markdown

coveralls commented May 25, 2026 •
edited
Loading

Coverage Status

coverage: 82.263% (-0.004%) from 82.267% — msteslov:add-markdown-linter into open-quantum-safe:main

@dstebila dstebila dismissed stale reviews from xuganyu96 and themself via a97d05c May 26, 2026 00:16
@dstebila dstebila requested review from Frauschi and bhess as code owners May 26, 2026 01:25
xuganyu96
xuganyu96 reviewed May 26, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@xuganyu96 xuganyu96 left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am sorry to have to walk back on my previous approval. The code change makes sense to me, but the choice of tool could use some justification. I did a quick search and found other markdown linters written in Ruby (markdownlint), Python (pymarkdown), and Rust (rumdl), and many others. It feels a tiny bit uncomfortable to introduce NPM into dev dependencies. I intuitively prefer keeping dev dependencies either in the Python ecosystem or as small binaries. Of course if markdownlint-cli is indeed a much more mature project than the other choices, then I am okay with introducing it into liboqs.

@msteslov
Add Markdown documentation linting
4d191da 
Signed-off-by: msteslov <msteslov@edu.hse.ru>
@msteslov msteslov force-pushed the add-markdown-linter branch from e7198e3 to 4d191da Compare May 30, 2026 12:48
@msteslov
Copy link
Copy Markdown
Author

msteslov commented May 30, 2026

Updated the PR to avoid the NPM dependency: it now uses rumdl==0.2.4 installed via Python/PyPI in CI, with a narrow .rumdl.toml rule set that passes on the existing documentation without unrelated Markdown churn. I also reduced the PR scope to only the workflow and linter configuration files.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@xuganyu96 xuganyu96 xuganyu96 left review comments

@baentsch baentsch Awaiting requested review from baentsch baentsch is a code owner

@dstebila dstebila Awaiting requested review from dstebila dstebila is a code owner

@Frauschi Frauschi Awaiting requested review from Frauschi

@bhess bhess Awaiting requested review from bhess

At least 2 approving reviews are required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

0.16.0

Development

Successfully merging this pull request may close these issues.

Add documentation Markdown linter to CI

4 participants

@msteslov @coveralls @dstebila @xuganyu96